Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

IXRecordTranscription

Adopted By:	no NEXTSTEP classes

Declared In:	indexing/protocols.h

Protocol Description

The IXRecordTranscription protocol is used by objects that archive other objects with the IXRecordWriting and IXRecordReading protocols to notify objects that they've been archived or unarchived by transcription.  Transcription is an efficient means of archiving in which an object's instance variables are written or read directly into or out of an archive.  Transcription avoids the overhead of the standard archiving mechanism (the write: and read: methods), but removes control of the archiving process from the object being archived.

Since transcription isn't done by the object being archived,  that object can't choose what data to archive and what data not to archive;  the transcriber simply writes all of the instance variables that it can.  However, there may be data that the transcriber doesn't archive that should be archived with the object.  If an object conforms to this protocol, the transcriber can notify it that it's being written or read, and the object can then ask the transcriber to store or retrieve any data that the transcriber would not.

There are two kinds of data that can't be transcribed:  data that aren't stored as instance variables (for example, the contents of a file or an entry in the defaults database), which the transcriber never knows about;  and untyped data (anything referred to by a pointer to void), whose length the transcriber can't determine.  These data are called blobs, and if the transcriber provides methods for storing themÐsetValue:andLength:ofBlob:forRecord: and getValue:andLength:ofBlob:forRecord:Ðthe object being transcribed can ask the transcriber to store or retrieve its blobs by name.  See the IXRecordManager class specification for descriptions of these methods.

Instance Methods

finishReading

- finishReading

Informs the receiver that it has been fully read into memory by a transcriber.  This allows the receiver to replace the unarchived object with a new object if necessary.  A finishReading message is sent to every object after it has been unarchived by a transcriber and sent a source:didReadRecord: message.  This method normally returns self.

Important:  The method description for finishUnarchiving in the Object class specification states that that method should return nil if no substitution is desired.  This isn't the case with this method.  The return value must be self if no substitution is desired;  returning nil will cause nil to be substituted for the object.

The finishReading message gives the application an opportunity to test an unarchived and initialized object to see whether it's usable, and, if not, to replace it with another object that is.  This method should return self if the unarchived instance is OK; otherwise, it should free the receiver and return another object to take its place.

See also:  - finishUnarchiving (Object)

source:didReadRecord:

- source:aTranscriber didReadRecord:(unsigned int)aHandle

Informs the receiver that it has been read into memory by aTranscriber, so it can perform any needed reinitialization.  If aTranscriber responds to getValue:andLength:ofBlob:forRecord: (as IXRecordManager does), the receiver can ask it to retrieve its blobs.  This method normally returns self, but the receiver may return a substitute, in which case the receiver is freed.

See also:  - getValue:andLength:ofBlob:forRecord: (IXRecordManager class)

source:willWriteRecord:

- source:aTranscriber willWriteRecord:(unsigned int)aHandle

Informs the receiver that it's about to be archived by aTranscriber.  If aTranscriber responds to setValue:andLength:ofBlob:forRecord: (as IXRecordManager does), the receiver can ask it to store its blobs.  This method normally returns self, but the receiver may return a substitute to be archived in its place, in which case the receiver is freed.

See also:  - setValue:andLength:ofBlob:forRecord: (IXRecordManager class)